HAL DCMI migration: List of applicable concepts ¶

This section provides information about the HAL DCMI applicable architecture concepts.

Concepts for DCMI ¶

Concept	Description
Separation of initialization and configuration functions	The initialization has been split into separate init and config steps: `HAL_DCMI_Init()`: initializes the handle and links it to a DCMI instance. `HAL_DCMI_PARALLEL_SetConfig()`: sets the configuration to the DCMI peripheral. `HAL_DCMI_SetConfigPipe()`: sets the configuration to a specific DCMI pipe.
Removal and conversion of init structure to configuration structure	The legacy init structure has been removed. Configuration is expressed through typed structs passed to feature-specific APIs.
Renaming of the handle structure	The handle structure has been renamed to `hal_dcmi_handle_t`.
Renaming unitary init structures	The structure `DCMI_InitTypeDef` has been replaced by `hal_dcmi_parallel_config_t` and dedicated configuration structures.
Remove MspInit and MspDeInit callbacks	The functions `HAL_DCMI_MspInit()` and `HAL_DCMI_MspDeInit()` have been removed and replaced by a user-defined sequence for DCMI initialization and configuration.
Unitary configuration APIs	New APIs have been introduced to get and set DCMI features.
Dedicated DMA link APIs replace generic __HAL_LINKDMA macro	DMA configuration and linking are explicit using DCMI APIs: `HAL_DCMI_SetDMA()`: attaches a DMA channel to DCMI. Dedicated DCMI functions manage DMA usage: configuration details are handled within the DCMI migration sequences.
Introduction of HAL user data set/get APIs	Two functions are available to set and get user data: `HAL_DCMI_SetUserData()` and `HAL_DCMI_GetUserData()`.
Individual callback registration APIs replace global register and unregister functions	Specific functions manage callback registration for each DCMI event, enabling the registration of callback functions for various DCMI events.
Introduce specialized IRQ handlers	A single IRQ handler forwards events, applications implement per-event callbacks for processing.
Revised and optimized HAL state machine	The DCMI state machine is reworked to ensure transitions of the peripheral functional states.
Revised and optimized HAL API status returns	Update DCMI functions to return: `HAL_INVALID_PARAM`: in case of NULL p_config structure pointer. `HAL_ERROR`: in case of error. `HAL_BUSY`: in case of process ongoing. `HAL_OK`: in case of operation completed successfully. `HAL_TIMEOUT`: in case of timeout occurrence.
Revised and optimized HAL error management	Redesign the error handling mechanisms within the HAL to enhance error detection, reporting, and management. This update aims to provide more detailed and consistent error information.
New APIs for filtering optional asynchronous process interrupts	New HAL DCMI start APIs with interrupt filtering capability, such as `HAL_DCMI_StartPipe_DMA_Opt()`.
Removal of underscore prefixes for macros	All underscore prefixes in DCMI driver have been removed.
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL DCMI driver have been removed and replaced by `_t`.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The `ASSERT_DBG_STATE` and `ASSERT_DBG_PARAM` macros are used to check the parameters and state of the HAL DCMI driver.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL DCMI header file may be available; macros, defines, functions, etc., in extension headers are adapted and merged into the main header.
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including DCMI instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL DCMI APIs start with `HAL_DCMI`.

Other HAL DCMI changes ¶

Concept	Consideration
Provide pipe concept.	To align with the DCMIPP HAL driver, which authorizes multiple capture pipes and to harmonize the HAL DCMI and HAL DCMIPP APIs, a pipe parameter was added to various capture APIs. This facilitates migration from peripherals using DCMI to those using DCMIPP. Note that the DCMI peripheral supports only one pipe, pipe 0.